home *** CD-ROM | disk | FTP | other *** search
/ Gigarom 1 / Gigarom Macintosh Archives (Quantum Leap)(CDRM1080320)(1993).iso / FILES / DEV / I-Z / ViewIt™ Shareware.sea / ViewIt™ 2.04 Shareware / FaceWare.rsrc / TEXT_1281_U8. String Lists.txt < prev    next >
Text File  |  1992-08-15  |  6KB  |  83 lines
  1. U8. String Lists
  2.   An important subset of UtilIt commands are those used to manipulate "string lists" (STR#-type resources or any relocatable block with a similar structure).  String lists contain Pascal-type strings packed together in a list:
  3.     [2-byte count][length byte][text][length byte][text]...
  4. Although this is a very efficient way to store strings, the only toolbox call, GetIndString, available for use with such string lists simply returns a particular string from an STR#-based list.
  5.   The four UtilIt commands GetStr, SetStr, SrtLst, and DupLst allow you to easily manipulate string lists.  For example, to set STR# 1040 equal to the first 10 elements of STR# 1030, you could write,
  6.  FaceIt(nil,SetStr,1040,-1,0,0); {clear list}
  7.  for i:= 1 to 10 do
  8.      begin
  9. {get ith string from STR# 1030}
  10.       FaceIt(nil,GetStr,1030,i,0,0);
  11. {set ith string in STR# 1040}
  12.       FaceIt(nil,SetStr,1040,i,0,0);
  13.      end;
  14. where each string being copied goes through the uString variable.  String lists can also be dynamically created and disposed of without the need for STR# resources.  For example, to copy the contents of STR# 1030 into a new string list handle, you could write: 
  15.     FaceIt(nil,DupLst,1030,0,0,0);
  16.     myList := uResult;
  17. where a handle to the new list is returned in uResult and saved in "myList".  Such a list handle can then be used with other string list commands.  For example,
  18.     FaceIt(nil,SetStr,myList,0,0,-1);
  19. would cause UtilIt to dispose of the dynamically allocated "myList" string list.
  20.   In some cases you may need to determine the number of strings which are currently in a list.  The first two bytes of the copy of the string list in memory contains this value.  For example, using Language Systems Fortran, where "n" is the number of strings in the list, "resID" is an STR# ID, and "strHdl" is the handle to a string list,
  21.  strHdl = GetResource(%val('STR#'),%val(resID))
  22.  n = word(long(strHdl))
  23. or, using Pascal, where the type "word" is declared as a pointer to an integer,
  24.  word = ^integer;
  25.  ...
  26.  strHdl := GetResource('STR#',resID);
  27.  n := word(strHdl^)^;
  28. or, using C,
  29.  strHdl = GetResource('STR#',resID);
  30.  n = *(short*)(*strHdl);
  31.  
  32.   The following commands use parameter a to designate a string list to manipulate.  Parameter a can refer to either an existing STR#-type resource or to any relocatable block in memory having the structure of a string list.  CAUTION:  A string list that is not based on an STR# resource must still have the structure of a string list.  An "empty" string list, for example, is not a 0-byte relocatable block created with the toolbox call NewHandle, but rather a 2-byte block containing the value zero.
  33.  
  34. GetStr  491  a,b,c,d,uString,uName
  35.   Gets a string or substring from a string list, uString, or uName, returning it in uString.
  36.   a = STR# resource ID of an existing string list resource
  37.     or a handle to an existing string list block in memory
  38.     or 0 = use uString or uName as source string
  39.   b = number of string in list to get
  40.     or 0 or 1 = use uString (if a = 0)
  41.     or 2 = use uName (if a = 0)
  42.     or other = address of a Pascal string (if a = 0)
  43.   c = number of substring within string to get
  44.     or 0 = return entire string (- d leading characters)
  45.   d = ASCII character number used to delimit substrings
  46.          (‚Äú,‚Äù = 44, ‚Äú:‚Äù = 58, ‚Äú;‚Äù = 59, etc.)
  47.     or number of leading characters to skip (if c = 0)
  48.  
  49. SetStr  492  a,b,c,d,uString,uResult
  50.   Adds, deletes, or inserts strings in string lists.  Where necessary, empty strings are added to the string list.  Note that uString is preserved across calls to SetStr.
  51.   a = STR# resource ID of an existing string list resource
  52.     or a handle to an existing string list block in memory
  53.     or, if a = 0, a new string list is created and its handle is
  54.         returned in uResult (save this handle for later use)
  55.   b = scope of changes to make
  56.    -1 = clear all strings in the list
  57.      0 = don't change any of the strings
  58.      n = nth string in list to manipulate
  59.   c = type of changes to make
  60.    -1 = delete nth string from list
  61.      0 = replace nth string in list with uString
  62.      1 = insert uString at nth string position
  63.   d = memory and disk options (disk operations are skipped if not working with an STR# resource)
  64.    -2 = delete copy of string list from memory w/o updating
  65.    -1 = update copy of string list in memory and on disk,
  66.             then delete the string list from memory
  67.      0 = update copy in memory only
  68.      1 = update both copy in memory and on disk
  69. You should, in general, minimize the number of calls made to update a copy of an STR# list on disk since this step involves saving the entire STR# resource back to disk.  In other words, if you have a loop which results in many SetStr calls, then don't ask UtilIt to update the disk copy (d = 1) until changes to the list in memory are complete.  There will often simply be no need to update the disk copy.
  70.  
  71. SrtLst  493  a,b
  72.   Sorts (alphabetizes) the list whose resource ID or handle is given by a.  Parameter b can be used to designate the number of leading characters to ignore when comparing strings in the list.
  73.  
  74. DupLst  494  a,b,c,d,uResult
  75.   Copies the list designated by parameter a to that designated by b, where a and b are either STR# IDs or handles to string lists.  If b is zero, then a new destination string list block is dynamically allocated and its handle returned in uResult.  Parameter c can be used to add or remove leading characters as each string is copied.  If c is positive, then c characters whose ASCII value is given by d are added to each string. If c is negative, then c characters are removed from the beginning of each copied string. If a = b, then the source string list is simply modified according to c and d.
  76.  
  77. GetI2  422  a,b,c,d,uString,uName,uI2
  78. GetI4  423  a,b,c,d,uString,uName,uI4
  79. GetR4  425  a,b,c,d,uString,uName,uR4
  80. GetR8  426  a,b,c,d,uString,uName,uR8
  81. GetR10  427  a,b,c,d,uString,uName,uR10
  82. GetR12  428  a,b,c,d,uString,uName,uR12
  83.   These commands are similar to GetStr, but return values in uI2 to uR12.  They assume that the string retrieved from the string list consists of bytes that are equal to an integer or real value.  GetI2, for example, moves the first two bytes of the designated string to uI2 (w/o converting the string to a number).  These commands are most often used to retrieve values from STR# 1101 after executing the FaceIt command GetFWs.